NGLVieweR - Visualize and interact with Protein Data Bank (PDB) files in R

Click here to view a Shiny application integrating most features of NGLVieweR.

Description

NGLvieweR provides an R interface to the NGL.js JavaScript library. It can be used to visualize and interact with protein data bank files (PDB) in R and Shiny applications. It includes a set of API functions to manipulate the viewer after creation and makes it possible to retrieve data from the visualization into R.

Installation

NGLVieweR is available through GitHub

install.packages("remotes")
remotes::install_github("nvelden/NGLVieweR")

Basics

You can load a PDB file directly or use a PDB code of a structure on RCSB.org. The below minimal example loads the PDB file and displays the structure in a “cartoon” representation.

#Load local pdb file
NGLVieweR("C:/7CID.pdb") %>%
addRepresentation("cartoon")

#Load protein by PDB code
NGLVieweR("7CID") %>%
addRepresentation("cartoon")

Functions

There are several functions to manipulate the viewer: - Hello - Test

You can view a “basic” NGLVieweR Shiny application by running the below code. Use “API” for an example using API calls or any of the function names (e.g “addSelection”") for function specific examples.

library(NGLVieweR)
library(shiny)
NGLVieweR_example("basic") 

Representations

You can load the structure as a “cartoon”, “ball+stick”, “line”, “surface”, “ribbon”, or any other representation listed in the NGL.js manual under “StructureRepresentation”. Multiple representations of the same structure can be overlaid by chaining the addSelection() function. Also see the “structure” tab in the demo app for a list of possible representations.

NGLVieweR("7CID") %>%
addRepresentation("cartoon") %>%
addRepresentation("ball+stick")

You can alter the appearance of select residues using the param argument. For a full list of options see the NGL.js “RepresentationParameters” and the “Selection language” section.

NGLVieweR("7CID") %>%
  addRepresentation("cartoon", param=list(colorScheme = "residueindex")) %>%
  addRepresentation("ball+stick", param=list(sele="233-248", 
                                             colorValue="red", 
                                             colorScheme="element")) %>%
  addRepresentation("surface", param=list(colorValue = "white", 
                                          opacity=0.1))

Stage

You can alter the background color or set the zoom or rotation speed using the stageParameters() function. For a full list of options, see the “StageParameters” method in the official NGL.js manual. Note: Changes in background color are not visible in the RStudio viewer.

NGLVieweR("7CID") %>%
 stageParameters(backgroundColor = "white", zoomSpeed = 1) %>%
 addRepresentation("cartoon", param = list(name = "cartoon", colorScheme="residueindex"))

Labels

Labels can be addded by setting the addRepresentation() type parameter to “label”. For a full list of of options, see the LabelRepresentationParameters section in the NGL.js manual. Also see the “label” tab in the demo app for possible label settings.

NGLVieweR("7CID") %>%
  addRepresentation("cartoon") %>%
  addRepresentation("ball+stick", param=list(colorScheme = "element",
                                             colorValue = "yellow",
                                             sele = "20")) %>%
  addRepresentation("label", param=list(sele="20",
                                        labelType="format",
                                        labelFormat='[%(resname)s]%(resno)s', #or enter custom text
                                        labelGrouping="residue", #or "atom" (eg. sele = "20:A.CB")
                                        color="white",
                                        fontFamiliy="sans-serif",
                                        xOffset = 1,
                                        yOffset = 0,
                                        zOffset = 0,
                                        fixedSize = TRUE,
                                        radiusType = 1,
                                        radiusSize = 1.5, #Label size
                                        showBackground=FALSE
                                        #backgroundColor="black",
                                        #backgroundOpacity=0.5,)
  )

Zoom

You can zoom into specific residues using the ZoomMove() function.

NGLVieweR("7CID") %>%
  addRepresentation("cartoon") %>%
  addRepresentation("ball+stick", param=list(colorScheme = "element",
                                             colorValue = "yellow",
                                             sele = "20")) %>%
  addRepresentation("label", param=list(sele="20",
                                        labelType="format",
                                        labelFormat='[%(resname)s]%(resno)s', #or enter custom text
                                        labelGrouping="residue", #or "atom" (eg. sele = "20:A.CB")
                                        color="white",
                                        xOffset = 1,
                                        fixedSize = TRUE,
                                        radiusType = 1,
                                        radiusSize = 1.5) #Label size
  ) %>%
  zoomMove(center = "20", 
           zoom = "20", 
           duration = 0, #animation time in ms 
           z_offSet = -20)

Shiny

The NGLVieweROutput() and renderNGLVieweR() functions enable you to visualize PDB files within Shiny applications. See the NGLVieweR_example("basic") and “API” for live examples.

library(shiny)
library(NGLVieweR)

ui = fluidPage(NGLVieweROutput("structure"))
server = function(input, output) {
  output$structure <- renderNGLVieweR({
    NGLVieweR("7CID") %>%
      addRepresentation("cartoon", param = list(name = "cartoon", color =
                                                  "residueindex")) %>%
      addRepresentation("ball+stick",
                        param = list(
                          name = "cartoon",
                          sele = '1-20',
                          colorScheme = "element"
                        )) %>%
      stageParameters(backgroundColor = "black") %>%
      setQuality("high") %>%
      setFocus(0) %>%
      setSpin(TRUE)
  })
}
shinyApp(ui, server)

API

In Shiny apps, you can manipulate the NGLVieweR widget after creation using specific “API” calls. You can for instance add or remove representations by refering to their name using the addSelection() or removeSelection() functions.

library(shiny)
library(NGLVieweR)

ui = fluidPage(
  titlePanel("Viewer with API inputs"),
  sidebarLayout(
    sidebarPanel(
      textInput("selection", "Selection", "1-20"),
      selectInput("type", "Type", c("ball+stick", "cartoon", "backbone")),
      selectInput("color", "Color", c("orange", "grey", "white")),
      actionButton("add", "Add"),
      actionButton("remove", "Remove")
    ),
    mainPanel(
      NGLVieweROutput("structure")
    )
  )
)
server = function(input, output) {
  output$structure <- renderNGLVieweR({
    NGLVieweR("7CID") %>%
      addRepresentation("cartoon", param = list(name = "cartoon", colorScheme="residueindex")) %>%
      stageParameters(backgroundColor = input$backgroundColor) %>%
      setQuality("high") %>%
      setFocus(0) %>%
      setSpin(TRUE)
  })
  observeEvent(input$add, {
    NGLVieweR_proxy("structure") %>%
      addSelection(isolate(input$type),
                   param =
                     list(name="sel1",
                          sele=isolate(input$selection),
                          colorValue=isolate(input$color)))
  })

  observeEvent(input$remove, {
    NGLVieweR_proxy("structure") %>%
      removeSelection("sel1")
  })
}
shinyApp(ui, server)

Possible API functions are:

  • addSelection()
  • removeSelection()
  • snapShot()
  • updateColor()
  • updateFocus()
  • updateFullscreen()
  • updateRepresentation()
  • updateRock()
  • updateSelection()
  • updateSpin()
  • updateStage()
  • updateVisibility()
  • updateZoomMove()